home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / LIB / REGEX / <tarZ$use> / files / RegEx / Doc next >
Text File  |  1992-01-12  |  4KB  |  112 lines
  1. Regular Expression matching functions.
  2.  
  3. Five functions are supplied.
  4.  
  5. 1. re_create(buffer,len,translate)
  6.  
  7.    Creates a regular expression buffer, re, of type (REGEX *). 
  8.    The user may supply three (optional) parameters. BUFFER and 
  9.    LEN define a user-supplied (fixed) buffer to hold the compiled 
  10.    regular expression. If this is not supplied, the package 
  11.    automatically allocates a buffer of the required size from the 
  12.    heap. TRANSLATE is a 256-character translation table for 
  13.    characters. If it is supplied, the package treats character c 
  14.    in all cases as if it were translate[c].
  15.  
  16. 2. re_free(re)
  17.  
  18.    Frees all storage associated with the regular expression 
  19.    buffer RE.
  20.  
  21. 3. re_compile(patt,re)
  22.  
  23.    Compiles the pattern string PATT into a regular expression 
  24.    buffer RE. Special characters (defined in the header file 
  25.    H.Chars) are as described below. The return value is 0 if the 
  26.    compile succeeds, or a pointer to an error message if it 
  27.    fails.
  28.  
  29. 4. re_anchored_match(re,str,len,start,mem)
  30.  
  31.    Matches string STR against the regular expression buffer RE. 
  32.    The match starts at position START in STR, and must match 
  33.    starting from there. The value returned is the number of 
  34.    characters matched or RE_FAIL if the match fails, or RE_ERROR 
  35.    if an error occurs. The optional argument LEN is the length of 
  36.    STR, and will be calculated if it is omitted (-1). The optional
  37.    argument MEM is a (REGMEM *) which will be filled with details
  38.    of the matched portions of the string. mem[0] holds the whole
  39.    matched string, and mem[1] to mem[9] hold the values matched 
  40.    by the regular expression memories \1 to \9.
  41.  
  42. 5. re_match(re,str,len,mem)
  43.  
  44.    Matches string STR against the regular expression buffer RE. 
  45.    The match may occur at any position in STR, and the value 
  46.    returned is the position of the start of the match (0 to 
  47.    strlen(str)), or RE_FAIL if the match fails, or RE_ERROR if an 
  48.    error occurs. The optional argument LEN is the length of STR,
  49.    and will be calculated if it is omitted (-1). The optional
  50.    argument MEM is a (REGMEM *) which will be filled with details
  51.    of the matched portions of the string. mem[0] holds the whole
  52.    matched string, and mem[1] to mem[9] hold the values matched by
  53.    the regular expression memories \1 to \9. Note that the only way
  54.    of finding the matched string is via mem[0].
  55.  
  56. Special characters.
  57.  
  58. The special characters which can be used in a regular expression 
  59. pattern are as follows:
  60.  
  61. Character expressions (ce's)
  62.  
  63.      ^         Start of a line
  64.      $         End of a line
  65.      \`        Start of the string
  66.      \'        End of the string
  67.      \<        Start of a word
  68.      \>        End of a word
  69.      \@        A word boundary
  70.      .         Any character
  71.      \w        A word character
  72.      [...]     A set of characters.
  73.      \c        Where `c' is a special character. Matches c.
  74.      c         Where `c' is any non-special character. Matches itself.
  75.  
  76. Operators
  77.  
  78.      ~         Not. `~ce' matches anything but ce.
  79.      |         Or. `re1 | re2' matches either re1 or re2.
  80.      *         Repeat. `re*' matches re repeated 0 or more times.
  81.      +         Many. `re+' matches re repeated 1 or more times.
  82.      ?         Optional. `re?' matches re or nothing.
  83.      (...)     Bracketing. `(re)' matches the same as re.
  84.  
  85. Memory.
  86.  
  87.      \{        Start memory.
  88.      \}        End memory.
  89.      \n        Match the characters in memory 'n' (n is 1-9).
  90.  
  91.    The operators \{...\} do not affect matching, but the
  92.    characters matched by the expression between the n'th \{ and
  93.    its corresponding \} are saved in memory n, for use in \n 
  94.    matches, and to return in the MEM array.
  95.  
  96. Words.
  97.  
  98.    Word characters are numbers and letters (ie. \w is the same as 
  99.    the expression [a-zA-Z0-9]). A word boundary is the position 
  100.    between a word character and a non-word character (in either 
  101.    order).
  102.  
  103. Character sets.
  104.  
  105.    Within sets, [...], all characters are taken literally, except \, 
  106.    ], and -. The '-' character indicates a range, unless it is the 
  107.    first or last character, when it indicates a literal '-'. The '\' 
  108.    character causes the following character to be taken literally 
  109.    (as in \-, \\, \]). In addition the normal C escape sequences \b, 
  110.    \f, \n, \r, \t, \v are available.
  111.  
  112.